home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 2000 October: Mac OS SDK / Dev.CD Oct 00 SDK1.toast / Development Kits / Cross Platform / QuickTime 4.1.2 Windows SDK / CIncludes / DigitalSignature.h < prev    next >
Encoding:
C/C++ Source or Header  |  2000-04-12  |  16.8 KB  |  410 lines  |  [TEXT/R*ch]
  1. /*
  2.      File:        DigitalSignature.h
  3.  
  4.      Contains:    Digital Signature Interfaces.
  5.  
  6.      Version:    Technology:    AOCE toolbox 1.02
  7.                  Release:    QuickTime 4.1
  8.  
  9.      Copyright:    (c) 1994-1999 by Apple Computer, Inc., all rights reserved.
  10.  
  11.      Bugs?:        For bug reports, consult the following page on
  12.                  the World Wide Web:
  13.  
  14.                      http://developer.apple.com/bugreporter/
  15.  
  16. */
  17. #ifndef __DIGITALSIGNATURE__
  18. #define __DIGITALSIGNATURE__
  19.  
  20. #ifndef __MACTYPES__
  21.     #include <MacTypes.h>
  22. #endif
  23.  
  24. #ifndef __MIXEDMODE__
  25.     #include <MixedMode.h>
  26. #endif
  27.  
  28. #ifndef __FILES__
  29.     #include <Files.h>
  30. #endif
  31.  
  32.  
  33.  
  34.  
  35. #if PRAGMA_ONCE
  36. #pragma once
  37. #endif
  38.  
  39. #ifdef __cplusplus
  40. extern "C" {
  41. #endif
  42.  
  43. #if PRAGMA_IMPORT
  44. #pragma import on
  45. #endif
  46.  
  47. #if PRAGMA_STRUCT_ALIGN
  48.     #pragma options align=mac68k
  49. #elif PRAGMA_STRUCT_PACKPUSH
  50.     #pragma pack(push, 2)
  51. #elif PRAGMA_STRUCT_PACK
  52.     #pragma pack(2)
  53. #endif
  54.  
  55. /* values of SIGNameAttributeType */
  56. enum {
  57.     kSIGCountryCode                = 0,
  58.     kSIGOrganization            = 1,
  59.     kSIGStreetAddress            = 2,
  60.     kSIGState                    = 3,
  61.     kSIGLocality                = 4,
  62.     kSIGCommonName                = 5,
  63.     kSIGTitle                    = 6,
  64.     kSIGOrganizationUnit        = 7,
  65.     kSIGPostalCode                = 8
  66. };
  67.  
  68. typedef unsigned short                     SIGNameAttributeType;
  69. /* 
  70. Certificate status codes returned in SIGCertInfo or SIGSignerInfo from
  71. either SIGGetCertInfo or SIGGetSignerInfo respectively. kSIGValid means that
  72. the certificate is currently valid. kSIGPending means the certificate is
  73. currently not valid - but will be.  kSIGExpired means the certificate has
  74. expired. A time is always associated with a SIGCertStatus.  In each case the
  75. time has a specific interpretation.  When the status is kSIGValid the time is
  76. when the certificate will expire. When the status is kSIGPending the time is
  77. when the certificate will become valid. When the status is kSIGExpired the time
  78. is when the certificate expired. In the SIGCertInfo structure, the startDate
  79. and endDate fields hold the appropriate date information.  In the SIGSignerInfo
  80. structure, this information is provided in the certSetStatusTime field. In the
  81. SIGSignerInfo struct, the status time is actually represented by the SIGSignatureStatus
  82. field which can contain any of the types below. NOTE: The only time you will get 
  83. a kSIGInvalid status is when it pertains to a SIGSignatureStatus field and only when
  84. you get a signature that was created after the certificates expiration date, something
  85. we are not allowing on the Mac but that may not be restricted on other platforms. Also, 
  86. it will not be possible to get a kSIGPending value for SIGSignatureStatus on the Mac but
  87. possibly allowed by other platforms.
  88. */
  89. /* Values for SIGCertStatus or SIGSignatureStatus */
  90. enum {
  91.     kSIGValid                    = 0,                            /* possible for either a SIGCertStatus or SIGSignatureStatus */
  92.     kSIGPending                    = 1,                            /* possible for either a SIGCertStatus or SIGSignatureStatus */
  93.     kSIGExpired                    = 2,                            /* possible for either a SIGCertStatus or SIGSignatureStatus * possible only for a SIGSignatureStatus */
  94.     kSIGInvalid                    = 3
  95. };
  96.  
  97. typedef unsigned short                     SIGCertStatus;
  98. typedef unsigned short                     SIGSignatureStatus;
  99. /* Number of bytes needed for a digest record when using SIGDigest */
  100. enum {
  101.     kSIGDigestSize                = 16
  102. };
  103.  
  104. typedef Byte                             SIGDigestData[16];
  105. typedef Byte *                            SIGDigestDataPtr;
  106.  
  107. struct SIGCertInfo {
  108.     unsigned long                     startDate;                    /* cert start validity date */
  109.     unsigned long                     endDate;                    /* cert end validity date */
  110.     SIGCertStatus                     certStatus;                    /* see comment on SIGCertStatus for definition */
  111.     unsigned long                     certAttributeCount;            /* number of name attributes in this cert */
  112.     unsigned long                     issuerAttributeCount;        /* number of name attributes in this certs issuer */
  113.     Str255                             serialNumber;                /* cert serial number */
  114. };
  115. typedef struct SIGCertInfo                SIGCertInfo;
  116. typedef SIGCertInfo *                    SIGCertInfoPtr;
  117.  
  118. struct SIGSignerInfo {
  119.     unsigned long                     signingTime;                /* time of signing */
  120.     unsigned long                     certCount;                    /* number of certificates in the cert set */
  121.     unsigned long                     certSetStatusTime;            /* Worst cert status time. See comment on SIGCertStatus for definition */
  122.     SIGSignatureStatus                 signatureStatus;            /* The status of the signature. See comment on SIGCertStatus for definition*/
  123. };
  124. typedef struct SIGSignerInfo            SIGSignerInfo;
  125. typedef SIGSignerInfo *                    SIGSignerInfoPtr;
  126.  
  127. struct SIGNameAttributesInfo {
  128.     Boolean                         onNewLevel;
  129.     Boolean                         filler1;
  130.     SIGNameAttributeType             attributeType;
  131.     ScriptCode                         attributeScript;
  132.     Str255                             attribute;
  133. };
  134. typedef struct SIGNameAttributesInfo    SIGNameAttributesInfo;
  135. typedef SIGNameAttributesInfo *            SIGNameAttributesInfoPtr;
  136.  
  137. typedef Ptr                             SIGContextPtr;
  138. typedef Ptr                             SIGSignaturePtr;
  139. /*
  140. Certificates are always in order. That is, the signers cert is always 0, the
  141. issuer of the signers cert is always 1 etc... to the number of certificates-1.
  142. You can use this constant for readability in your code.
  143. */
  144. enum {
  145.     kSIGSignerCertIndex            = 0
  146. };
  147.  
  148. /*
  149. Call back procedure supplied by developer, return false to cancel the current
  150. process.
  151. */
  152. typedef CALLBACK_API( Boolean , SIGStatusProcPtr )(void );
  153. typedef STACK_UPP_TYPE(SIGStatusProcPtr)                         SIGStatusUPP;
  154. #if OPAQUE_UPP_TYPES
  155.     EXTERN_API(SIGStatusUPP)
  156.     NewSIGStatusUPP                   (SIGStatusProcPtr        userRoutine);
  157.  
  158.     EXTERN_API(void)
  159.     DisposeSIGStatusUPP               (SIGStatusUPP            userUPP);
  160.  
  161.     EXTERN_API(Boolean)
  162.     InvokeSIGStatusUPP               (SIGStatusUPP            userUPP);
  163.  
  164. #else
  165.     enum { uppSIGStatusProcInfo = 0x00000010 };                     /* pascal 1_byte Func() */
  166.     #define NewSIGStatusUPP(userRoutine)                             (SIGStatusUPP)NewRoutineDescriptor((ProcPtr)(userRoutine), uppSIGStatusProcInfo, GetCurrentArchitecture())
  167.     #define DisposeSIGStatusUPP(userUPP)                             DisposeRoutineDescriptor(userUPP)
  168.     #define InvokeSIGStatusUPP(userUPP)                             (Boolean)CALL_ZERO_PARAMETER_UPP((userUPP), uppSIGStatusProcInfo)
  169. #endif
  170. /* support for pre-Carbon UPP routines: NewXXXProc and CallXXXProc */
  171. #define NewSIGStatusProc(userRoutine)                             NewSIGStatusUPP(userRoutine)
  172. #define CallSIGStatusProc(userRoutine)                            InvokeSIGStatusUPP(userRoutine)
  173. /*
  174. Resource id's of standard signature icon suite, all sizes and colors are available.
  175. */
  176. enum {
  177.     kSIGSignatureIconResID        = -16797,
  178.     kSIGValidSignatureIconResID    = -16799,
  179.     kSIGInvalidSignatureIconResID = -16798
  180. };
  181.  
  182. /* ------------------------------- CONTEXT CALLS ------------------------------- 
  183. To use the Digital Signature toolbox you will need a SIGContextPtr.  To create
  184. a SIGContextPtr you simply call SIGNewContext and it will create and initialize
  185. a context for you.  To free the memory occupied by the context and invalidate
  186. its internal data, call SIGDisposeContext. An initialized context has no notion
  187. of the type of operation it will be performing however, once you call
  188. SIGSignPrepare SIGVerifyPrepare, or SIGDigestPrepare, the contexts operation
  189. type is set and to switch  to another type of operation will require creating a
  190. new context. Be sure to pass the same context to corresponding toolbox calls
  191. (ie SIGSignPrepare, SIGProcessData, SIGSign)  in other words mixing lets say
  192. signing and verify calls with the same context is not allowed.
  193. */
  194. EXTERN_API( OSErr )
  195. SIGNewContext                    (SIGContextPtr *        context)                            FOURWORDINLINE(0x203C, 0x0002, 0x076C, 0xAA5D);
  196.  
  197. EXTERN_API( OSErr )
  198. SIGDisposeContext                (SIGContextPtr             context)                            FOURWORDINLINE(0x203C, 0x0002, 0x076D, 0xAA5D);
  199.  
  200.  
  201. /* ------------------------------- SIGNING CALLS ------------------------------- 
  202. Once you have created a SIGContextPtr, you create a signature by calling
  203. SIGSignPrepare once, followed by n calls to SIGProcessData, followed by one call
  204. toRcpt SIGSign. To create another signature on different data but for the same
  205. signer, don't dispose of the context and call SIGProcessData for the new data
  206. followed by a call SIGSign again. In this case the signer will not be prompted
  207. for their signer and password again as it was already provided.  Once you call
  208. SIGDisposeContext, all signer information will be cleared out of the context and
  209. the signer will be re-prompted.  The signer file FSSpecPtr should be set to nil
  210. if you want the toolbox to use the last signer by default or prompt for a signer
  211. if none exists.  The prompt parameter can be used to pass a string to be displayed
  212. in the dialog that prompts the user for their password.  If the substring "^1"
  213. (without the quotes) is in the prompt string, then the toolbox will replace it
  214. with the name of the signer from the signer selected by the user.  If an empty
  215. string is passed, the following default string will be sent to the toolbox
  216. "\pSigning as ^1.".  You can call any of the utility routines after SIGSignPrepare
  217. or SIGSign to get information about the signer or certs.
  218. */
  219. EXTERN_API( OSErr )
  220. SIGSignPrepare                    (SIGContextPtr             context,
  221.                                  const FSSpec *            signerFile,
  222.                                  ConstStr255Param         prompt,
  223.                                  Size *                    signatureSize)                        FOURWORDINLINE(0x203C, 0x0008, 0x076E, 0xAA5D);
  224.  
  225. EXTERN_API( OSErr )
  226. SIGSign                            (SIGContextPtr             context,
  227.                                  SIGSignaturePtr         signature,
  228.                                  SIGStatusUPP             statusProc)                            FOURWORDINLINE(0x203C, 0x0006, 0x076F, 0xAA5D);
  229.  
  230.  
  231. /* ------------------------------- VERIFYING CALLS ------------------------------- 
  232. Once you have created a SIGContextPtr, you verify a signature by calling
  233. SIGVerifyPrepare  once, followed by n calls to SIGProcessData, followed by one
  234. call to SIGVerify. Check the return code from SIGVerify to see if the signature
  235. verified or not (noErr is returned on  success otherwise the appropriate error
  236. code).  Upon successfull verification, you can call any of the utility routines
  237. toRcpt find out who signed the data.
  238. */
  239. EXTERN_API( OSErr )
  240. SIGVerifyPrepare                (SIGContextPtr             context,
  241.                                  SIGSignaturePtr         signature,
  242.                                  Size                     signatureSize,
  243.                                  SIGStatusUPP             statusProc)                            FOURWORDINLINE(0x203C, 0x0008, 0x0770, 0xAA5D);
  244.  
  245. EXTERN_API( OSErr )
  246. SIGVerify                        (SIGContextPtr             context)                            FOURWORDINLINE(0x203C, 0x0002, 0x0771, 0xAA5D);
  247.  
  248. /* ------------------------------ DIGESTING CALLS ------------------------------ 
  249. Once you have created a SIGContextPtr, you create a digest by calling
  250. SIGDigestPrepare once, followed by n calls to SIGProcessData, followed by one
  251. call to SIGDigest.  You can dispose of the context after SIGDigest as the
  252. SIGDigestData does not reference back into it.  SIGDigest returns the digest in
  253. digest.
  254. */
  255. EXTERN_API( OSErr )
  256. SIGDigestPrepare                (SIGContextPtr             context)                            FOURWORDINLINE(0x203C, 0x0002, 0x0772, 0xAA5D);
  257.  
  258. EXTERN_API( OSErr )
  259. SIGDigest                        (SIGContextPtr             context,
  260.                                  SIGDigestData             digest)                                FOURWORDINLINE(0x203C, 0x0004, 0x0773, 0xAA5D);
  261.  
  262.  
  263. /* ------------------------------ PROCESSING DATA ------------------------------ 
  264. To process data during a digest, sign, or verify operation call SIGProcessData
  265. as many times as necessary and with any sized blocks of data.  The data needs to
  266. be processed in the same order during corresponding sign and verify operations
  267. but does not need to be processed in the same sized chunks (i.e., the toolbox
  268. just sees it as a continuous bit stream).
  269. */
  270. EXTERN_API( OSErr )
  271. SIGProcessData                    (SIGContextPtr             context,
  272.                                  const void *            data,
  273.                                  Size                     dataSize)                            FOURWORDINLINE(0x203C, 0x0006, 0x0774, 0xAA5D);
  274.  
  275.  
  276. /* ------------------------------- UTILITY CALLS ------------------------------- 
  277. Given a context that has successfully performed a verification SIGShowSigner
  278. will  display a modal dialog with the entire distinguished name of the person
  279. who signed the data. the prompt (if supplied) will appear at the top of the
  280. dialog.  If no prompt is specified, the default prompt "\pVerification
  281. Successfull." will appear.
  282.  
  283. Given a context that has been populated by calling SIGSignPrepare, SIGSign or a
  284. successful SIGVerify, you can make the remaining utility calls:
  285.  
  286. SIGGetSignerInfo will return the SignerInfo record.  The certCount can be used
  287. toRcpt index into the certificate set when calling SIGGetCertInfo,
  288. SIGGetCertNameAttributes or SIGGetCertIssuerNameAttributes. The signingTime is
  289. only defined if the call is made after SIGSign  or SIGVerify. The certSetStatus
  290. will tell you the best status of the entire certificate set while
  291. certSetStatusTime will correspond to the time associated with that status (see
  292. definitions above).
  293.  
  294. SIGGetCertInfo will return the SIGCertInfo record when given a valid index into
  295. the cert set in  certIndex.  Note: The cert at index kSIGSignerCertIndex is
  296. always the signers certificate.  The  serial number, start date and end date
  297. are there should you wish to display that info.  The  certAttributeCount and
  298. issuerAttributeCount provide the number of parts in the name of that certificate
  299. or that certificates issuer respectively.  You use these numbers to index into
  300. either SIGGetCertNameAttributes or SIGGetCertIssuerNameAttributes to retrieve
  301. the name. The certStatus will tell you the status of the certificate while
  302. certStatusTime will correspond to the time associated with that status (see
  303. definitions above).
  304.  
  305. SIGGetCertNameAttributes and SIGGetCertIssuerNameAttributes return name parts
  306. of the certificate at  certIndex and attributeIndex.  The newLevel return value
  307. tells you wether the name attribute returned is at the same level in the name
  308. hierarchy as the previous attribute.  The type return value tells you  the type
  309. of attribute returned. nameAttribute is the actual string containing the name
  310. attribute.   So, if you wanted to display the entire distinguished name of the
  311. person who's signature was just validated you could do something like this;
  312.  
  313.     (...... variable declarations and verification code would preceed this sample ......)
  314.  
  315.     error = SIGGetCertInfo(verifyContext, kSIGSignerCertIndex, &certInfo);
  316.     HandleErr(error);
  317.  
  318.     for (i = 0; i <= certInfo.certAttributeCount-1; i++)
  319.         {
  320.         error = SIGGetCertNameAttributes(
  321.             verifyContext, kSIGSignerCertIndex, i, &newLevel, &type, theAttribute);
  322.         HandleErr(error);
  323.         DisplayNamePart(theAttribute, type, newLevel);
  324.         }
  325. */
  326. EXTERN_API( OSErr )
  327. SIGShowSigner                    (SIGContextPtr             context,
  328.                                  ConstStr255Param         prompt)                                FOURWORDINLINE(0x203C, 0x0004, 0x0775, 0xAA5D);
  329.  
  330. EXTERN_API( OSErr )
  331. SIGGetSignerInfo                (SIGContextPtr             context,
  332.                                  SIGSignerInfo *        signerInfo)                            FOURWORDINLINE(0x203C, 0x0004, 0x0776, 0xAA5D);
  333.  
  334. EXTERN_API( OSErr )
  335. SIGGetCertInfo                    (SIGContextPtr             context,
  336.                                  unsigned long             certIndex,
  337.                                  SIGCertInfo *            certInfo)                            FOURWORDINLINE(0x203C, 0x0006, 0x0777, 0xAA5D);
  338.  
  339. EXTERN_API( OSErr )
  340. SIGGetCertNameAttributes        (SIGContextPtr             context,
  341.                                  unsigned long             certIndex,
  342.                                  unsigned long             attributeIndex,
  343.                                  SIGNameAttributesInfo * attributeInfo)                        FOURWORDINLINE(0x203C, 0x0008, 0x0778, 0xAA5D);
  344.  
  345. EXTERN_API( OSErr )
  346. SIGGetCertIssuerNameAttributes    (SIGContextPtr             context,
  347.                                  unsigned long             certIndex,
  348.                                  unsigned long             attributeIndex,
  349.                                  SIGNameAttributesInfo * attributeInfo)                        FOURWORDINLINE(0x203C, 0x0008, 0x0779, 0xAA5D);
  350.  
  351.  
  352.  
  353. /* --------------------------- FILE SIGN & VERIFY CALLS -------------------------- 
  354. These calls allow you to detect the presence of a standard signtaure in a file as 
  355. well as sign and verify files in a standard way.  An example of this is the Finder, 
  356. which uses these calls to allow the user to "drop sign" a file.
  357.  
  358. To detect if a file is signed in the standard way, pass the FSSpec of the file to SIGFileIsSigned.
  359. A result of noErr means the file is in fact signed, otherwise, a kSIGNoSignature error will
  360. be returned.
  361.  
  362. Once you have created a SIGContextPtr, you can make calls to either sign or verify a file in
  363. a standard way: 
  364.  
  365. To sign a file, call SIGSignPrepare followed by 'n' number of calls to SIGSignFile,
  366. passing it the file spec for each file you wish to sign in turn.  You supply the context, the signature 
  367. size that was returned from SIGSignPrepare and an optional call back proc.  The call will take care of all
  368. the processing of data and affixing the signature to the file. If a signature already exists in the file, 
  369. it is replaced with the newly created signature.
  370.  
  371. To verify a file that was signed using SIGSignFile, call SIGVerifyFile passing it a new context and 
  372. the file spec.  Once this call has completed, if the verification is successfull, you can pass the context 
  373. to SIGShowSigner to display the name of the person who signed the file.
  374. */
  375. EXTERN_API( OSErr )
  376. SIGFileIsSigned                    (const FSSpec *            fileSpec)                            FOURWORDINLINE(0x203C, 0x0002, 0x09C4, 0xAA5D);
  377.  
  378. EXTERN_API( OSErr )
  379. SIGSignFile                        (SIGContextPtr             context,
  380.                                  Size                     signatureSize,
  381.                                  const FSSpec *            fileSpec,
  382.                                  SIGStatusUPP             statusProc)                            FOURWORDINLINE(0x203C, 0x0008, 0x09C5, 0xAA5D);
  383.  
  384. EXTERN_API( OSErr )
  385. SIGVerifyFile                    (SIGContextPtr             context,
  386.                                  const FSSpec *            fileSpec,
  387.                                  SIGStatusUPP             statusProc)                            FOURWORDINLINE(0x203C, 0x0006, 0x09C6, 0xAA5D);
  388.  
  389.  
  390. #if PRAGMA_STRUCT_ALIGN
  391.     #pragma options align=reset
  392. #elif PRAGMA_STRUCT_PACKPUSH
  393.     #pragma pack(pop)
  394. #elif PRAGMA_STRUCT_PACK
  395.     #pragma pack()
  396. #endif
  397.  
  398. #ifdef PRAGMA_IMPORT_OFF
  399. #pragma import off
  400. #elif PRAGMA_IMPORT
  401. #pragma import reset
  402. #endif
  403.  
  404. #ifdef __cplusplus
  405. }
  406. #endif
  407.  
  408. #endif /* __DIGITALSIGNATURE__ */
  409.  
  410.